package com.walker.taogong.datasource;

import javax.sql.DataSource;

/**
 * A DataSourceProvider registers a JDBC DataSource in a JNDI Naming context
 * under the name of "jdbc/anaconda".
 * <p>
 * Clients can retrieve the datasource by JNDI lookup.
 * <p>
 * Till Hibernate 3.6 / ConnectionPooling this interface was implicitely
 * declaring a Singleton.
 * Starting with Hibernate 3.6 / ConnectionPooling this interface is implemented
 * multiple times.
 * 
 * @author HWellmann
 */
public interface DataSourceProvider
{
    /**
     * JNDI subcontext for the datasource name.
     */
    public static final String TAOGONG_DATASOURCE_SUBCONTEXT = "jdbc";
    
    /**
     * Relative name of datasource.
     */
    public static final String TAOGONG_DATASOURCE_KEY = "taogong";
    
    /**
     * Name for datasource lookup in JNDI.
     */
    public static final String TAOGONG_DATASOURCE_JNDI_KEY = 
            TAOGONG_DATASOURCE_SUBCONTEXT + "/" + TAOGONG_DATASOURCE_KEY;

    /**
     * Registers a datasource in JNDI under the name of 
     * {@link #TAOGONG_DATASOURCE_JNDI_KEY}.
     */
    public void registerDataSource();
    
    public void closeChainedDataSource();
    
    /**
     * Read data source for chained data source usage.
     * @return DataSource as is already created.
     */
    public DataSource getDataSource();
    
    /**
     * Defines the parent data source to be used.
     * Chaining is not supported by all DataSourceProvider implementations.
     * @param chain Parent DataSourceProvider object
     */
    public void setChainedDataSource(DataSourceProvider chain);
    
    /**
     * Configuration flavors of the datasource
     * @return Array of flavors, e.g. "postgres" or "c3p0"
     */
    public String[] getFlavors();
}
